Skip to content

MQ-1267 Change queues oldestMessageTimestamp to use kj::Date#6445

Closed
KennethRuan wants to merge 2 commits intocloudflare:mainfrom
KennethRuan:kruan/enhance-queues-oldest-message-timestamp-type
Closed

MQ-1267 Change queues oldestMessageTimestamp to use kj::Date#6445
KennethRuan wants to merge 2 commits intocloudflare:mainfrom
KennethRuan:kruan/enhance-queues-oldest-message-timestamp-type

Conversation

@KennethRuan
Copy link
Copy Markdown
Contributor

Summary

In previous PRs, new metrics were added to the Queues API surface.

#6246
#6354
#6339

As pointed out in #6246, it would be clearer to return a JS Date for oldestMessageTimestamp. This PR implements that change so that oldestMessageTimestamp in the three APIs modified above, all return Date | undefined instead of number.

Changes

This PR includes changes to queue.c++ and queue.h features that are gated behind an experimental flag, as such they are non-breaking. We also make a correction to the metrics() method to use JSG_REQUIRE_NONNULL (see here).

Sentinel Value
We wanted to surface oldestMessageTimestamp as Date | undefined to the user. However, since Date(0) (JS Date at the UNIX epoch) and undefined appear the same over the wire, we opt to treat the zero value as a sentinel and manually set it to kj::none so that it appears as undefined to the end user.

An additional test was also added to ensure that the sentinel value is handled properly.

Testing

  • bazel test //src/workerd/api/tests:queue-metrics-sentinel-test@
  • bazel test //src/workerd/api/tests:queue-metrics-sentinel-test@all-compat-flags

@KennethRuan KennethRuan requested review from a team as code owners March 27, 2026 19:10
@KennethRuan KennethRuan force-pushed the kruan/enhance-queues-oldest-message-timestamp-type branch 2 times, most recently from d73a4e7 to 1b54323 Compare March 27, 2026 21:14
Copy link
Copy Markdown
Member

@npaun npaun left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Otherwise, seems legit.

@KennethRuan KennethRuan force-pushed the kruan/enhance-queues-oldest-message-timestamp-type branch from 1b54323 to b48718e Compare April 1, 2026 15:23
@npaun
Copy link
Copy Markdown
Member

npaun commented Apr 1, 2026

/bigbonk review dis

Copy link
Copy Markdown
Contributor

@ask-bonk ask-bonk bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good. The change from number to Date | undefined is well-motivated, the sentinel-clearing approach is clean, and the parseQueueResponse template nicely consolidates the repeated parse-and-fixup pattern per npaun's earlier suggestion.

A few minor observations below, but nothing blocking.

@ask-bonk
Copy link
Copy Markdown
Contributor

ask-bonk bot commented Apr 1, 2026

Review submitted. Here's a summary of what I found:

Overall: Approved. The PR cleanly changes oldestMessageTimestamp from number to Date | undefined across all three queue API paths (metrics, send, sendBatch) and the consumer-side batch handler. The sentinel approach (treating 0/epoch as "no data" → undefined) is well-documented and consistently applied.

Key observations posted as inline comments:

  1. parseQueueResponse template (queue.c++:46) — The auto third parameter works but makes the expected accessor signature less discoverable. A concept or explicit type would help readability.

  2. Long comment line (queue.h:32) — The "Callers MUST call clearEpochSentinel()..." comment exceeds typical line length.

  3. Comment scope (queue.c++:26) — The clearEpochSentinel comment reads as a general pattern for "timestamp fields" but it's only used for oldestMessageTimestamp.

  4. Float truncation (queue.c++:685) — The static_cast<int64_t> on the capnp Float64 silently truncates fractional milliseconds. Probably fine since the wire format uses integer ms, but flagged for awareness.

github run

@npaun
Copy link
Copy Markdown
Member

npaun commented Apr 2, 2026

Merge executed via #6481

@npaun npaun closed this Apr 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants